@npmcli/map-workspaces

What is @npmcli/map-workspaces?

The @npmcli/map-workspaces package is designed to assist with managing and interacting with npm workspaces. It provides functionality to map and iterate over workspaces in a project, allowing for operations such as executing scripts or installing dependencies in each workspace. This can be particularly useful in monorepo setups where multiple packages are managed within a single repository.

What are @npmcli/map-workspaces's main functionalities?

Mapping Workspaces

This feature allows you to map all the workspaces defined in your project. The code sample demonstrates how to use @npmcli/map-workspaces to retrieve a list of workspaces based on the configuration in your package.json. This is useful for scripts that need to perform actions on each workspace.

const mapWorkspaces = require('@npmcli/map-workspaces');
const { workspaces } = await mapWorkspaces({
  cwd: process.cwd(),
  pkg: {
    workspaces: [
      'packages/*'
    ]
  }
});
console.log(workspaces);

Other packages similar to @npmcli/map-workspaces

lerna

Lerna is a tool for managing JavaScript projects with multiple packages, known as a monorepo. It provides similar functionalities to @npmcli/map-workspaces by allowing you to run scripts, publish packages, and more across multiple workspaces. However, Lerna is more feature-rich and can handle complex workflows, including versioning and publishing.

yarn-workspaces

Yarn Workspaces is a feature built into Yarn that automatically manages the installation of dependencies and linking of packages in a monorepo. It offers similar workspace mapping functionalities but is tightly integrated with Yarn's package management capabilities. Unlike @npmcli/map-workspaces, Yarn Workspaces is not a separate package but a feature of Yarn itself.

README

@npmcli/map-workspaces

Retrieves a name:pathname Map for a given workspaces config.

Long version: Reads the workspaces property from a valid workspaces configuration object and traverses the paths and globs defined there in order to find valid nested packages and return a Map of all found packages where keys are package names and values are folder locations.

Install

npm install @npmcli/map-workspaces

Usage:

const mapWorkspaces = require('@npmcli/map-workspaces')
await mapWorkspaces({
  cwd,
  pkg: {
    workspaces: {
      packages: [
        "a",
        "b"
      ]
    }
  }
})
// ->
// Map {
//   'a': '<cwd>/a'
//   'b': '<cwd>/b'
// }

Examples:

Glob usage:

Given a folder structure such as:

├── package.json
└── apps
   ├── a
   │   └── package.json
   ├── b
   │   └── package.json
   └── c
       └── package.json

const mapWorkspaces = require('@npmcli/map-workspaces')
await mapWorkspaces({
  cwd,
  pkg: {
    workspaces: [
      "apps/*"
    ]
  }
})
// ->
// Map {
//   'a': '<cwd>/apps/a'
//   'b': '<cwd>/apps/b'
//   'c': '<cwd>/apps/c'
// }

API:

mapWorkspaces(opts) -> Promise<Map>

• opts:
  • pkg: A valid package.json Object
  • cwd: A String defining the base directory to use when reading globs and paths.
  • ignore: An Array of paths to be ignored when using globs to look for nested package.
  • ...Also support all other glob options

Returns

A Map in which keys are package names and values are the pathnames for each found workspace.

LICENSE

ISC

Changelog

4.0.2 (2024-11-20)

Bug Fixes

• ae9cd9e #176 ignore ENOTDIR errors (#176) (@brianlenz)

Chores

• 84d179f #174 bump @npmcli/template-oss from 4.23.3 to 4.23.4 (#174) (@dependabot[bot], @npm-cli-bot)